home *** CD-ROM | disk | FTP | other *** search
/ Risc World 3 / Risc World 3.iso / SOFTWARE / ISSUE4 / POWERBASE / DOCS / _AppendixA next >
Text File  |  2001-10-30  |  6KB  |  119 lines
  1. ===========================================
  2. Appendix A − Powerbase as an Impulse server
  3. ===========================================
  4.  
  5. The following is a description of the Impulse “methods” understood by
  6. Powerbase, given in the standard format recommended by Computer Concepts.
  7. Users wishing to write their own Impulse tasks to communicate with Powerbase
  8. will need this information. They will also need details of the SWIs to which
  9. Impulse will respond, and this information is obtainable from Computer
  10. Concepts.    
  11.  
  12.      {methods:  GetPathname
  13.                 Selection <string>
  14.                 ParseQuery <string>
  15.                 GetField <tag>
  16.                 GetRecord
  17.                 PutRecord
  18.                 ExpandCode <string>
  19.                 GetExpanded <string>
  20.                 NextMatch
  21.  
  22. Description:
  23.  
  24. GetPathname specifies an “object” i.e. a Powerbase database. If Powerbase
  25. has the required database open it replies with the full pathname of the
  26. object, otherwise it returns an error message. Example of use:
  27.  
  28.         :Powerbase !Elements GetPathname  (returns pathname of !Elements)
  29.  
  30. R6 points to pathname when calling task is decoding reply.
  31.  
  32. Selection <string> tells Powerbase about a field, or group of fields, in
  33. which the caller is interested. The fields are specified as a list of tags,
  34. separated by any suitable character (e.g. “/” or “,”). The same separator
  35. must appear at the very end of the tag-list.  Powerbase replies with the
  36. maximum data-length of the combined fields in the selection. Example of
  37. use:
  38.  
  39.         :Powerbase Selection NAME/SYM/Z/
  40.  
  41. R6 points to a string which gives data-length.
  42.  
  43. ParseQuery <string> informs Powerbase of the criteria to be used in
  44. selecting records to transmit to the caller.  The parameter is a standard
  45. Powerbase search formula and Powerbase replies with the title which would
  46. normally appear at the head of one of its printed lists. Example of use:
  47.  
  48.         :Powerbase ParseQuery GP=T
  49.  
  50. R6 points to returned title.
  51.  
  52. GetField <tag> requests from Powerbase the data in the specified field of
  53. the next record which matches the preceding ParseQuery command.  When
  54. Powerbase replies to the GetField command the calling task should respond
  55. with an Impulse_FetchData, specifying the address and length of the buffer
  56. to be used, and then wait for an Impulse_Receive event (reason code &204)
  57. before reading the buffer.  Example of use:
  58.  
  59.         :Powerbase GetField NAME
  60.  
  61. GetRecord [<key>] (The square brackets signify that the key is optional:
  62. they are not part of the command.) Sent without a key it requests from
  63. Powerbase the next record which matches the preceding ParseQuery command. If
  64. the primary key of a record in the database is appended then Powerbase will
  65. return the record corresponding to that key. The key must be separated from
  66. the GetRecord by a space. The calling task must follow the procedure
  67. described above for GetField.  Powerbase will transmit the fields specified
  68. in the Selection command, using the same separator as was used in that
  69. command. Receipt of data may be followed by another GetRecord command,
  70. returning the next matching record and so on, a zero-length response
  71. signifying that there are no more matching records. If using keys to request
  72. specific records you should end by sending *** as a key to tell Powerbase
  73. that the dialogue is finished.  This command and the one below operate only
  74. on Subfile 0 of the Powerbase database. Example of use:
  75.  
  76.         :Powerbase GetRecord ACTI
  77.  
  78. PutRecord informs Powerbase that the caller wishes to write a record to the
  79. current Powerbase database. It should be sent as message type &200. A
  80. Selection command should have been previously sent to tell Powerbase what
  81. fields to expect and what separator is to be used. Powerbase will then reply
  82. with a GetRecord command (reason code &201) which the caller should
  83. acknowledge with message type &202, specifying the maximum length of the
  84. data which will be sent. Wait for event &203 which is a request by Powerbase
  85. for the caller to transmit the data. The caller should then do so with
  86.  
  87.                                 - 63 -
  88.  
  89. Impulse_TransmitData, specifying the buffer address and the length of data
  90. being sent. This may be immediately followed by  another PutRecord.
  91.  
  92. ExpandCode <string> requests the expanded form of a code used in a field
  93. linked to a validation table. The parameter string consists of the code
  94. itself, then a space, then the name of the validation table with the column
  95. number appended. Example of use:
  96.  
  97.         :Powerbase ExpandCode T Group0
  98.  
  99. GetExpanded <string> combines the functions of GetField and ExpandCode, i.e.
  100. it requests the expanded form of the contents of a specified field. The
  101. parameter is the tag of the field. It is not necessary to supply the name of
  102. the validation table or number of the linked column since Powerbase can
  103. determine these from the entry in the Link file linking the field to the
  104. table. By default the second column of the table (i.e. column 1) is used to
  105. supply the expanded string, but this may be overrridden by appending the
  106. relevant column number preceded by a comma as in the second example.
  107. Remember that the first column is numbered 0. Examples of use:
  108.  
  109.         :Powerbase GetExpanded GP      :Powerbase GetExpanded GP,2    
  110.  
  111. NextMatch is designed to remove the restriction whereby only the data from a
  112. single record can be merged into a given document.  All it does is tell
  113. Powerbase to access the next record matching the search formula in the Merge
  114. window and interpret subsequent Merge commands by taking data from that
  115. record.
  116.  
  117. }
  118.  
  119.                                 - 64 -